<?php

///////////////////////////////////////////////////////////////////////////////
/**
 * This file contains the {@link IConnector} interface.
 *
 * System requirements:
 * <ul>
 * <li>PHP 5</li>
 * </ul>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * The Connector library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * {@link http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License}
 * for more details.
 *
 * @author Per Egil Roksvaag
 * @copyright 2009 Per Egil Roksvaag
 * @license http://www.gnu.org/copyleft/lesser.html GNU Lesser General Public License
 * @package connector
 * @version 2.0.0
 */

///////////////////////////////////////////////////////////////////////////////
/**
 * Use this constant as a shortcut for linebreaks in SQL queries.
 */

define("LB", "\r\n");

///////////////////////////////////////////////////////////////////////////////
/**
 * The IConnector interface defines the function signatures and
 * the constants for all connector classes.
 *
 * If you want your application to run with different types of databases,
 * you may ONLY use the functions defined here.
 *
 * You may implement additional IConnector classes from scratch using this
 * interface, but that is not recommended. Mostly, you'll want to <b>extend</b>
 * the abstract {@link BaseConnector} class.
 *
 * @tutorial connector.pkg
 * @tutorial connector.pkg#extend
 * @package connector
 */

interface IConnector
{
	///////////////////////////////////////////////////////////////////////////
	/**
	 * The name of the connection character set (used by MySQL).
	 */
	const CONN_CHARSET = "CONN_CHARSET";

	/**
	 * The name of the default database to use or a ODBC Data Source.
	 */
	const CONN_DATABASE = "CONN_DATABASE";

	/**
	 * The name of the server host to connect to (ignored by ODBC).
	 */
	const CONN_HOSTNAME = "CONN_HOSTNAME";

	/**
	 * The database password. Leave empty (null) to use Windows authentification.
	 */
	const CONN_PASSWORD = "CONN_PASSWORD";

	/**
	 * Opens a persistent connection to a database when true.
	 */
	const CONN_PERSISTENT = "CONN_PERSISTENT";

	/**
	 * The database user name. Leave empty (null) to use Windows authentification.
	 */
	const CONN_USERNAME = "CONN_USERNAME";

	const CONN_DRIVER = "CONN_DRIVER";
	const CONN_PORT = "CONN_PORT";
	const CONN_NATIVE = "CONN_NATIVE";
	const CONN_POOL = "CONN_POOL";

	/**
	 * Set this option to the character set being used by your application.
	 */
	const CHAR_APPLICATION = "CHAR_APPLICATION";

	/**
	 * Set this option to the character set being used by your database(s).
	 */
	const CHAR_DATABASE = "CHAR_DATABASE";

	/**
	 * Writes debug information in the php log file when true.
	 */
	const LOG_DEBUG = "LOG_DEBUG";

	/**
	 * Error information is written in the php log file when true.
	 */
	const LOG_ERROR = "LOG_ERROR";

	/**
	 * Throws an ConnectorException on db operation failure then true.
	 */
	const THROW_EXCEPTION = "THROW_EXCEPTION";

	/**
	 * Set this option to true to cast numeric strings to int or float.
	 */
	const PARAM_CAST_NUMERIC = "PARAM_CAST_NUMERIC";

	/**
	 * True, when named placeholders are used, false otherwise.
	 */
	const PARAM_NAMED = "PARAM_NAMED";

	/**
	 * The parameter prefix to be used in parameterized queries.
	 */
	const PARAM_PREFIX = "PARAM_PREFIX";

	/**
	 * Set this option to true to send sql statements as parameterized queries
	 * to the database.
	 */
	const PARAM_QUERIES = "PARAM_QUERIES";

	/**
	 * Strips magic quotes from string parameters when true.
	 */
	const PARAM_STRIP_MAGIC = "PARAM_STRIP_MAGIC";

	/**
	 * Strips all PHP and HTML tags from string parameters when true.
	 */
	const PARAM_STRIP_TAGS = "PARAM_STRIP_TAGS";

	/**
	 * Removes leading and trailing white space from string parameters when true.
	 */
	const PARAM_TRIM = "PARAM_TRIM";

	/**
	 * Value to insert into the SQL query then an array parameter is empty.
	 */
	const PARAM_EMPTY_ARRAY_VALUE = "PARAM_EMPTY_ARRAY_VALUE";

	/**
	 * Enables internal caching of all tables (query results) returned by the
	 * select() function when true.
	 */
	const RESULT_CACHE = "RESULT_CACHE";

	/**
	 * When defined, the select() function returns the query result
	 * table as an ASSOCIATED array of rows (which again are associated
	 * arrays).
	 */
	const RESULT_KEY_FIELD = "RESULT_KEY_FIELD";

	/**
	 * The maximum number of rows returend by the {@link select()} method.
	 */
	const RESULT_LENGTH = "RESULT_LENGTH";

	/**
	 * The number of rows to skip from the beginning of query result table
	 * returned by the {@link select()} method.
	 */
	const RESULT_OFFSET = "RESULT_OFFSET";

	///////////////////////////////////////////////////////////////////////////
	/**
	 * Send a SQL SELECT query to the database and get the query result.
	 *
	 * As a default, this function returns a <b>table</b> as a numeric array of
	 * rows. Each <b>row</b> is an associated array. The array keys in
	 * the rows correspond to the column names of your query.
	 *
	 * @tutorial connector.pkg#retrieve
	 * @param string $query A SQL query to execute on a database.
	 * @param array $param An associated array of values to be used in the $query.
	 * @param array $map An array of type definitions for the <var>$param</var> values.
	 * @param array $options An associated array of options, see the {@tutorial connector.pkg#options.element}.
	 * @throws Exception when $param doesn't match the type definition $map.
	 * @return array The query result as a table (array of associated arrays).
	 */

	public function select($query, $param = array(), $map = array(), $options = array());

	///////////////////////////////////////////////////////////////////////////
	/**
	 * Send a SQL INSERT query to the database and get the IDENTITY ID
	 * generated from the last INSERT operation (if any).
	 *
	 * @tutorial connector.pkg#modify.insert
	 * @param string $query A SQL query to execute on a database.
	 * @param array $param An associated array of values to be used in the $query.
	 * @param array $map An array of type definitions for the <var>$param</var> values.
	 * @param array $options An associated array of options, see the {@tutorial connector.pkg#options.element}.
	 * @throws Exception when $param doesn't match the type definition $map.
	 * @return int The IDENTITY ID of the last inserted row.
	 */

	public function insert($query, $param = array(), $map = array(), $options = array());

	///////////////////////////////////////////////////////////////////////////
	/**
	 * Send a SQL UPDATE query to the database and get the number of rows
	 * updates by the query.
	 *
	 * @tutorial connector.pkg#modify.update
	 * @param string $query A SQL query to execute on a database.
	 * @param array $param An associated array of values to be used in the $query.
	 * @param array $map An array of type definitions for the <var>$param</var> values.
	 * @param array $options An associated array of options, see the {@tutorial connector.pkg#options.element}.
	 * @throws Exception when $param doesn't match the type definition $map.
	 * @return int The number of rows updates by the query.
	 */

	public function update($query, $param = array(), $map = array(), $options = array());

	///////////////////////////////////////////////////////////////////////////
	/**
	 * Send a SQL DELETE query to the database and get the number of rows
	 * deleted by the query.
	 *
	 * @tutorial connector.pkg#modify.delete
	 * @param string $query A SQL query to execute on a database.
	 * @param array $param An associated array of values to be used in the $query.
	 * @param array $map An array of type definitions for the <var>$param</var> values.
	 * @param array $options An associated array of options, see the {@tutorial connector.pkg#options.element}.
	 * @throws Exception when $param doesn't match the type definition $map.
	 * @return int The number of rows deleted by the query.
	 */

	public function delete($query, $param = array(), $map = array(), $options = array());

	///////////////////////////////////////////////////////////////////////////
	/**
	 * Begins a transaction on the current connection.
	 * The current transaction includes all statements on the connection that
	 * were executed after the call to transaction() and before any calls
	 * to rollback() or commit().
	 *
	 * @param array $options An associated array of options, see the {@tutorial connector.pkg#options.element}.
	 * @return bool true if the transaction was successfully begun, false otherwise.
	 */
	
	public function transaction($options = array());
	
	///////////////////////////////////////////////////////////////////////////
	/**
	 * Commits the current transaction on the current connection.
	 * The current transaction includes all statements on the connection that
	 * were executed after the call to transaction() and before any calls
	 * to rollback() or commit().
	 *
	 * @param array $options An associated array of options, see the {@tutorial connector.pkg#options.element}.
	 * @return bool true if the transaction was successfully committed, false otherwise.
	 */
	
	public function commit($options = array());
	
	///////////////////////////////////////////////////////////////////////////
	/**
	 * Rolls back the current transaction on the current connection. 
	 * The current transaction includes all statements on the connection that
	 * were executed after the call to transaction() and before any calls
	 * to rollback() or commit().
	 *
	 * @param array $options An associated array of options, see the {@tutorial connector.pkg#options.element}.
	 * @return bool true if the transaction was successfully rolled back, false otherwise.
	 */
	
	public function rollback($options = array());
	
	///////////////////////////////////////////////////////////////////////////
	/**
	 * Get the database link identifier used by the IConnector instance.
	 * @return resource A PHP database link identifier.
	 */

	public function getLink();

	///////////////////////////////////////////////////////////////////////////
	/**
	 * Get an array of all currently used options or the value of the
	 * option defined in the optional $element parameter.
	 *
	 * @param string $element An option constant, see the {@tutorial connector.pkg#options.element}.
	 * @return mixed All options as an associated array or the value of a single option.
	 */

	public function getOptions($element = null);

	///////////////////////////////////////////////////////////////////////////
	/**
	 * Set one or more options for the IConnector instance.
	 * Some options are only valid as constructor or function options.
	 *
	 * @param mixed $options Multiple options as an associated array or the value of a single option.
	 * @param string $element An option constant, see the {@tutorial connector.pkg#options.element}.
	 * @return mixed The previous option value(s).
	 */

	public function setOptions($options, $element = null);

	///////////////////////////////////////////////////////////////////////////
}

?>